@filigran/chatbot 3.20.0 → 3.21.0

package/CHANGELOG.md

@@ -8,7 +8,18 @@ the versions follow [semantic versioning](https://semver.org/spec/v2.0.0.html).
 This file starts at 3.10.0; earlier releases are on the
 [releases page](https://github.com/FiligranHQ/filigran-ui/releases).
 
-## 3.20.0 — unreleased
+## 3.21.0 — unreleased
+
+### Added
+
+- `onConversationChange` says why the conversation changed: its second argument
+  is `{ created }`, true for a conversation the panel has just created from a
+  new chat (its first message or file), false for one opened from the list, on
+  a reload or in place of a deleted one, and when it is left for a new chat. A
+  host could not tell an opened conversation from a created one, as both came
+  after a new chat.
+
+## 3.20.0 — 2026-11-10
 
 ### Added
 

package/README.md

@@ -105,7 +105,7 @@ import { ChatPanel } from '@filigran/chatbot';
 | `composerToolbar`   | `React.ReactNode`                         | —            | Extra controls appended to the composer toolbar. The escape hatch for host-specific affordances (XTM One's session-tool picker) — the package never learns what they are. Pass nothing and the toolbar simply has none. |
 | `storageKeyPrefix`  | `string`                                  | —            | Namespaces every key the panel keeps in browser storage (`<prefix>:filigranChatConversationId`, …), for a host mounting more than one panel |
 | `conversationId`    | `string \| null`                          | —            | The conversation on screen when the host owns it (a `?c=` URL); `null` is a new chat. Left `undefined`, the panel remembers its own, and a host-owned one is never written to storage |
-| `onConversationChange` | `(id: string \| null) => void`         | —            | Called whenever the conversation on screen changes, whoever changed it (a first answer, New chat, the history) |
+| `onConversationChange` | `(id: string \| null, change: { created: boolean }) => void` | —            | Called whenever the conversation on screen changes, whoever changed it (a first answer, New chat, the history); `created` is true for one the panel has just created from a new chat (its first message or file) |
 | `initialAgent`      | `string`                                  | —            | Agent selected once the list loads, by id or slug, over the remembered one |
 | `onAgentChange`     | `(agent: XtmAgent) => void`               | —            | Called when another agent is picked, in the menu or by opening a conversation of another agent: the picker follows the conversation on screen |
 | `readOnly`          | `boolean`                                 | `false`      | Hides the composer: a conversation the user may read but not write to |

package/dist/index.d.ts

@@ -618,8 +618,14 @@ interface ChatPanelProps {
      * is a new chat. Left `undefined`, the panel remembers its own.
      */
     conversationId?: string | null;
-    /** Called whenever the conversation on screen changes, whoever changed it. */
-    onConversationChange?: (conversationId: string | null) => void;
+    /**
+     * Called whenever the conversation on screen changes, whoever changed it.
+     * `created` is true for a conversation the panel has just created from a new
+     * chat (its first message or file), false for one opened or left (the list, a
+     * reload, a new chat) and for one the backend put in place of a deleted one
+     * that was opened.
+     */
+    onConversationChange?: (conversationId: string | null, change: ChatConversationChange) => void;
     /** Agent selected once the list loads, by id or slug, over the remembered one. */
     initialAgent?: string;
     /**
@@ -954,6 +960,11 @@ interface ChatStreamEventInfo {
     /** The frame acknowledges a turn replayed from its start (`thinking` with `resumed`). */
     replayed?: boolean;
 }
+/** Why the conversation on screen changed (see `onConversationChange`). */
+interface ChatConversationChange {
+    /** The panel has just created this conversation from a new chat; false when it was opened, replaced or left. */
+    created: boolean;
+}
 /** What a host can do to a mounted panel, through its `ref`. */
 interface ChatPanelHandle {
     /** Send *text* as the user, leaving the composer's own draft alone; resolves to what became of it. */
@@ -1429,4 +1440,4 @@ interface TransferredAgent {
 declare const voiceCallSupported: () => boolean;
 
 export { ChatPanel, ChatToggleButton, voiceCallSupported };
-export type { AgentStatusState, ApiEndpoints, BackendType, ChatAnsweredBy, ChatArtifact, ChatArtifactKind, ChatAttachment, ChatCodeBlockContext, ChatCodeBlockRenderer, ChatContextBreakdown, ChatContextUsage, ChatConversationAction, ChatConversationRef, ChatConversationReferenceCandidate, ChatConversationSummary, ChatFile, ChatFileRefusal, ChatHeaderContext, ChatHeldOutcome, ChatMarkerContext, ChatMarkerRenderer, ChatMessage, ChatMessagePersistedFeedback, ChatMessageSlotContext, ChatMode, ChatPanelHandle, ChatPanelMode, ChatPanelProps, ChatPanelTheme, ChatPromptTemplate, ChatQuotaStatus, ChatSendDecision, ChatSendDraft, ChatSendOptions, ChatSendOutcome, ChatSidebarSearch, ChatStreamEventInfo, ChatToggleButtonProps, ChatToolLabels, ChatTurnEnd, ChatTurnOutcome, ChatWorkspace, ConsultStatus, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };
+export type { AgentStatusState, ApiEndpoints, BackendType, ChatAnsweredBy, ChatArtifact, ChatArtifactKind, ChatAttachment, ChatCodeBlockContext, ChatCodeBlockRenderer, ChatContextBreakdown, ChatContextUsage, ChatConversationAction, ChatConversationChange, ChatConversationRef, ChatConversationReferenceCandidate, ChatConversationSummary, ChatFile, ChatFileRefusal, ChatHeaderContext, ChatHeldOutcome, ChatMarkerContext, ChatMarkerRenderer, ChatMessage, ChatMessagePersistedFeedback, ChatMessageSlotContext, ChatMode, ChatPanelHandle, ChatPanelMode, ChatPanelProps, ChatPanelTheme, ChatPromptTemplate, ChatQuotaStatus, ChatSendDecision, ChatSendDraft, ChatSendOptions, ChatSendOutcome, ChatSidebarSearch, ChatStreamEventInfo, ChatToggleButtonProps, ChatToolLabels, ChatTurnEnd, ChatTurnOutcome, ChatWorkspace, ConsultStatus, MessageFeedback, ToolApprovalDecision, ToolApprovalProposal, ToolApprovalVerdict, TransferredAgent, Translate, XtmAgent };